package com.zenithmind.document.service;

import com.zenithmind.document.pojo.vo.DocumentStatisticsVO;

/**
 * 文档统计服务接口
 * 遵循接口隔离原则：专注于统计功能
 * 遵循单一职责原则：只负责文档统计相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentStatisticsService {

    /**
     * 获取文档统计信息
     * 
     * @param documentId 文档ID
     * @return 统计信息
     */
    DocumentStatisticsVO getDocumentStatistics(String documentId);

    /**
     * 记录文档访问
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param accessType 访问类型
     * @return 是否成功
     */
    Boolean recordDocumentAccess(String documentId, String userId, String accessType);

    /**
     * 增加下载次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean incrementDownloadCount(String documentId, String userId);

    /**
     * 增加查看次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean incrementViewCount(String documentId, String userId);

    /**
     * 增加收藏次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean incrementFavoriteCount(String documentId, String userId);

    /**
     * 减少收藏次数
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean decrementFavoriteCount(String documentId, String userId);

    /**
     * 更新文档评分
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param rating 评分
     * @return 是否成功
     */
    Boolean updateDocumentRating(String documentId, String userId, Double rating);

    /**
     * 获取用户统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息
     */
    Object getUserStatistics(String userId);

    /**
     * 获取分类统计信息
     * 
     * @param categoryId 分类ID
     * @return 统计信息
     */
    Object getCategoryStatistics(String categoryId);

    /**
     * 获取系统统计信息
     * 
     * @return 统计信息
     */
    Object getSystemStatistics();

    /**
     * 获取热门文档统计
     * 
     * @param limit 限制数量
     * @return 统计信息
     */
    Object getHotDocumentsStatistics(Integer limit);

    /**
     * 获取访问趋势统计
     * 
     * @param documentId 文档ID
     * @param days 天数
     * @return 统计信息
     */
    Object getAccessTrendStatistics(String documentId, Integer days);

    /**
     * 清理过期统计数据
     * 
     * @param days 保留天数
     * @return 清理数量
     */
    Integer cleanupExpiredStatistics(Integer days);
}
